<!doctype html>


<html>
<head>
  <link rel="shortcut icon" href="static/images/favicon.ico" type="image/x-icon">
  <title>safestyle.js (Closure Library API Documentation - JavaScript)</title>
  <link rel="stylesheet" href="static/css/base.css">
  <link rel="stylesheet" href="static/css/doc.css">
  <link rel="stylesheet" href="static/css/sidetree.css">
  <link rel="stylesheet" href="static/css/prettify.css">

  <script>
     var _staticFilePath = "static/";
     var _typeTreeName = "goog";
     var _fileTreeName = "Source";
  </script>

  <script src="static/js/doc.js">
  </script>


  <meta charset="utf8">
</head>

<body onload="grokdoc.onLoad();">

<div id="header">
  <div class="g-section g-tpl-50-50 g-split">
    <div class="g-unit g-first">
      <a id="logo" href="index.html">Closure Library API Documentation</a>
    </div>

    <div class="g-unit">
      <div class="g-c">
        <strong>Go to class or file:</strong>
        <input type="text" id="ac">
      </div>
    </div>
  </div>
</div>





<div class="colmask rightmenu">
<div class="colleft">
    <div class="col1">
      <!-- Column 1 start -->

<div id="title">
       <span class="fn">safestyle.js</span>
</div>

<div class="g-section g-tpl-75-25">
  <div class="g-unit g-first" id="description">
    <span class='nodesc'>No description.</span>
  </div>
  

        <div class="g-unit" id="useful-links">
          <div class="title">Useful links</div>
          <ol>
            <li><a href="local_closure_goog_html_safestyle.js.source.html"><span class='source-code-link'>Source Code</span></a></li>
            <li><a href="http://code.google.com/p/closure-library/source/browse/local/closure/goog/html/safestyle.js">Git</a></li>
          </ol>
        </div>
</div>

<h2 class="g-first">File Location</h2>
  <div class="g-section g-tpl-20-80">
    <div class="g-unit g-first">
      <div class="g-c-cell code-label">/goog/html/safestyle.js</div>
    </div>
  </div>
<hr/>


  <h2>Classes</h2>
 <div class="fn-constructor">
        <a href="class_goog_html_SafeStyle.html">
          goog.html.SafeStyle</a><br/>
        <div class="class-details">A string-like object which represents a sequence of CSS declarations
(<code> propertyName1: propertyvalue1; propertyName2: propertyValue2; ...</code>)
and that carries the security type contract that its value, as a string,
will not cause untrusted script execution (XSS) when evaluated as CSS in a
browser.

Instances of this type must be created via the factory method,
(<code> goog.html.SafeStyle.fromConstant</code>), and not by invoking its
constructor. The constructor intentionally takes no parameters and the type
is immutable; hence only a default instance corresponding to the empty
string can be obtained via constructor invocation.

A SafeStyle's string representation (<code> #getSafeStyleString()</code>) can
safely:
<ul><li>Be interpolated as the entire content of a *quoted* HTML style
      attribute, or before already existing properties. The SafeStyle string
      *must be HTML-attribute-escaped* (where " and ' are escaped) before
      interpolation.
  <li>Be interpolated as the entire content of a {}-wrapped block within a
      stylesheet, or before already existing properties. The SafeStyle string
      should not be escaped before interpolation. SafeStyle's contract also
      guarantees that the string will not be able to introduce new properties
      or elide existing ones.
  <li>Be assigned to the style property of a DOM node. The SafeStyle string
      should not be escaped before being assigned to the property.
</li></li></li></ul>

A SafeStyle may never contain literal angle brackets. Otherwise, it could
be unsafe to place a SafeStyle into a &lt;style&gt; tag (where it can't
be HTML escaped). For example, if the SafeStyle containing
"<code> font: 'foo &amp;lt;style/&amp;gt;&amp;lt;script&amp;gt;evil&amp;lt;/script&amp;gt;'</code>" were
interpolated within a &lt;style&gt; tag, this would then break out of the
style context into HTML.

A SafeStyle may contain literal single or double quotes, and as such the
entire style string must be escaped when used in a style attribute (if
this were not the case, the string could contain a matching quote that
would escape from the style attribute).

Values of this type must be composable, i.e. for any two values
<code> style1</code> and <code> style2</code> of this type,
<code> style1.getSafeStyleString() + style2.getSafeStyleString()</code> must
itself be a value that satisfies the SafeStyle type constraint. This
requirement implies that for any value <code> style</code> of this type,
<code> style.getSafeStyleString()</code> must not end in a "property value" or
"property name" context. For example, a value of <code> background:url("</code>
or <code> font-</code> would not satisfy the SafeStyle contract. This is because
concatenating such strings with a second value that itself does not contain
unsafe CSS can result in an overall string that does. For example, if
<code> javascript:evil())"</code> is appended to <code> background:url("</code>, the
resulting string may result in the execution of a malicious script.

TODO(user): Consider whether we should implement UTF-8 interchange
validity checks and blacklisting of newlines (including Unicode ones) and
other whitespace characters (\t, \f). Document here if so and also update
SafeStyle.fromConstant().

The following example values comply with this type's contract:
<ul><li><pre class="lang-js prettyprint">width: 1em;</pre><li><pre class="lang-js prettyprint">height:1em;</pre><li><pre class="lang-js prettyprint">width: 1em;height: 1em;</pre><li><pre class="lang-js prettyprint">background:url('<a href="http://url">http://url</a>');</pre></li></li></li></li></ul>
In addition, the empty string is safe for use in a CSS attribute.

The following example values do NOT comply with this type's contract:
<ul><li><pre class="lang-js prettyprint">background: red</pre> (missing a trailing semi-colon)
  <li><pre class="lang-js prettyprint">background:</pre> (missing a value and a trailing semi-colon)
  <li><pre class="lang-js prettyprint">1em</pre> (missing an attribute name, which provides context for
      the value)
</li></li></li></ul></div>
 </div>
      
<br/>

  <div class="legend">
        <span class="key publickey"></span><span>Public</span>
        <span class="key protectedkey"></span><span>Protected</span>
        <span class="key privatekey"></span><span>Private</span>
  </div>









<div class="section">
  <table class="horiz-rule">


  </table>
</div>




  <h2>Global Functions</h2>





<div class="section">
  <table class="horiz-rule">


     <tr class="even entry private">
       <td class="access"></td>






  <td>
    <a name="goog.html.SafeStyle.createSafeStyleSecurityPrivateDoNotAccessOrElse_"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.SafeStyle.</span><span class="entryName">createSafeStyleSecurityPrivateDoNotAccessOrElse_<span class="args">(<span class="arg">style</span>)</span>
        </span>
        &#8658; <span>!</span><span class="type"><a href="class_goog_html_SafeStyle.html">goog.html.SafeStyle</a></span>
      </div>


     <div class="entryOverview">
       Utility method to create SafeStyle instances.

This function is considered "package private", i.e. calls (using "suppress
visibility") from other files within this package are considered acceptable.
DO NOT call this function from outside the goog.html package; use appropriate
wrappers instead.


     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">style</span>
        : <span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span>
        <div class="entryOverview">The string to initialize the SafeStyle object with.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<span>!</span><span class="type"><a href="class_goog_html_SafeStyle.html">goog.html.SafeStyle</a></span>&nbsp;
            The initialized SafeStyle object.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safestyle.js.source.html#line264">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.html.SafeStyle.fromConstant"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.SafeStyle.</span><span class="entryName">fromConstant<span class="args">(<span class="arg">style</span>)</span>
        </span>
        &#8658; <span>!</span><span class="type"><a href="class_goog_html_SafeStyle.html">goog.html.SafeStyle</a></span>
      </div>


     <div class="entryOverview">
       Creates a SafeStyle object from a compile-time constant string.

<code> style</code> should be in the format
<code> name: value; [name: value; ...]</code> and must not have any &lt; or &gt;
characters in it. This is so that SafeStyle's contract is preserved,
allowing the SafeStyle to correctly be interpreted as a sequence of CSS
declarations and without affecting the syntactic structure of any
surrounding CSS and HTML.

This method performs basic sanity checks on the format of <code> style</code>
but does not constrain the format of <code> name</code> and <code> value</code>, except
for disallowing tag characters.


     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">style</span>
        : <span>!</span><span class="type"><a href="class_goog_string_Const.html">goog.string.Const</a></span>
        <div class="entryOverview">A compile-time-constant string from which
    to create a SafeStyle.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<span>!</span><span class="type"><a href="class_goog_html_SafeStyle.html">goog.html.SafeStyle</a></span>&nbsp;
            A SafeStyle object initialized to
    <code> style</code>.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safestyle.js.source.html#line159">code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.html.SafeStyle.unwrap"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.SafeStyle.</span><span class="entryName">unwrap<span class="args">(<span class="arg">safeStyle</span>)</span>
        </span>
        &#8658; <span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span>
      </div>


     <div class="entryOverview">
       Performs a runtime check that the provided object is indeed a
SafeStyle object, and returns its value.


     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">safeStyle</span>
        : <span>!</span><span class="type"><a href="class_goog_html_SafeStyle.html">goog.html.SafeStyle</a></span>
        <div class="entryOverview">The object to extract from.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span>&nbsp;
            The safeStyle object's contained string, unless
    the run-time type check fails. In that case, <code> unwrap</code> returns an
    innocuous string, or, if assertions are enabled, throws
    <code> goog.asserts.AssertionError</code>.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safestyle.js.source.html#line228">code &raquo;</a>
  </td>
     </tr>


  </table>
</div>






      <!-- Column 1 end -->
    </div>

        <div class="col2">
          <!-- Column 2 start -->
          <div class="col2-c">
            <h2 id="ref-head">Directory html</h2>
            <div id="localView"></div>
          </div>

          <div class="col2-c">
            <h2 id="ref-head">File Reference</h2>
            <div id="sideFileIndex" rootPath="" current="/goog/html/safestyle.js"></div>
          </div>
          <!-- Column 2 end -->
        </div>
</div>
</div>

</body>
</html>
